home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_exim.idb / usr / freeware / catman / p_man / cat3 / pcreposix.Z / pcreposix
Encoding:
Text File  |  1999-01-26  |  7.7 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      PPPPCCCCRRRREEEE((((3333))))               UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV               PPPPCCCCRRRREEEE((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       pcreposix - POSIX API    for Perl-compatible regular
  10.       expressions.
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.       ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccrrrreeeeppppoooossssiiiixxxx....hhhh>>>>
  14.  
  15.       iiiinnnntttt rrrreeeeggggccccoooommmmpppp((((rrrreeeeggggeeeexxxx____tttt ****_p_r_e_g, const char    *_p_a_t_t_e_r_n,
  16.            iiiinnnntttt _c_f_l_a_g_s);
  17.  
  18.       iiiinnnntttt rrrreeeeggggeeeexxxxeeeecccc((((rrrreeeeggggeeeexxxx____tttt ****_p_r_e_g, const char    *_s_t_r_i_n_g,
  19.            ssssiiiizzzzeeee____tttt _n_m_a_t_c_h, regmatch_t _p_m_a_t_c_h[], int _e_f_l_a_g_s);
  20.  
  21.       ssssiiiizzzzeeee____tttt rrrreeeeggggeeeerrrrrrrroooorrrr((((iiiinnnntttt _e_r_r_c_o_d_e, const regex_t *_p_r_e_g,
  22.            cccchhhhaaaarrrr ****_e_r_r_b_u_f, size_t _e_r_r_b_u_f__s_i_z_e);
  23.  
  24.       vvvvooooiiiidddd rrrreeeeggggffffrrrreeeeeeee((((rrrreeeeggggeeeexxxx____tttt ****_p_r_e_g);
  25.  
  26.  
  27.  
  28.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  29.       This set of functions    provides a POSIX-style API to the PCRE
  30.       regular expression package. See ppppccccrrrreeee ((((3333)))) for a description
  31.       of the native    API, which contains additional functionality.
  32.       The functions    described here are just    wrapper    functions that
  33.       ultimately call the native API.
  34.  
  35.       As I am pretty ignorant about    POSIX, these functions must be
  36.       considered as    experimental. I    have implemented only those
  37.       option bits that can be reasonably mapped to PCRE native
  38.       options. Other POSIX options are not even defined. It    may be
  39.       that it is useful to define, but ignore, other options.
  40.       Feedback from    more knowledgeable folk    may cause this kind of
  41.       detail to change.
  42.  
  43.       When PCRE is called via these    functions, it is only the API
  44.       that is POSIX-like in    style. The syntax and semantics    of the
  45.       regular expressions themselves are still those of Perl,
  46.       subject to the setting of various PCRE options, as described
  47.       below.
  48.  
  49.       The header for these functions is supplied as    ppppccccrrrreeeeppppoooossssiiiixxxx....hhhh to
  50.       avoid    any potential clash with other POSIX libraries.    It
  51.       can, of course, be renamed or    aliased    as rrrreeeeggggeeeexxxx....hhhh, which is
  52.       the "correct"    name. It provides two structure    types, _r_e_g_e_x__t
  53.       for compiled internal    forms, and _r_e_g_m_a_t_c_h__t for returning
  54.       captured substrings. It also defines some constants whose
  55.       names    start with "REG_"; these are used for setting options
  56.       and identifying error    codes.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 12/10/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      PPPPCCCCRRRREEEE((((3333))))               UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV               PPPPCCCCRRRREEEE((((3333))))
  71.  
  72.  
  73.  
  74.      CCCCOOOOMMMMPPPPIIIILLLLIIIINNNNGGGG AAAA PPPPAAAATTTTTTTTEEEERRRRNNNN
  75.       The function rrrreeeeggggccccoooommmmpppp(((()))) is called to compile a    pattern    into
  76.       an internal form. The    pattern    is a C string terminated by a
  77.       binary zero, and is passed in    the argument _p_a_t_t_e_r_n. The _p_r_e_g
  78.       argument is a    pointer    to a regex_t structure which is    used
  79.       as a base for    storing    information about the compiled
  80.       expression.
  81.  
  82.       The argument _c_f_l_a_g_s is either    zero, or contains one or more
  83.       of the bits defined by the following macros:
  84.  
  85.         REG_ICASE
  86.  
  87.       The PCRE_CASELESS option is set when the expression is
  88.       passed for compilation to the    native function.
  89.  
  90.         REG_NEWLINE
  91.  
  92.       The PCRE_MULTILINE option is set when    the expression is
  93.       passed for compilation to the    native function.
  94.  
  95.       The yield of rrrreeeeggggccccoooommmmpppp(((()))) is zero on success, and non-zero
  96.       otherwise. The _p_r_e_g structure    is filled in on    success, and
  97.       one member of    the structure is publicized: _r_e__n_s_u_b contains
  98.       the number of    capturing subpatterns in the regular
  99.       expression. Various error codes are defined in the header
  100.       file.
  101.  
  102.  
  103.  
  104.      MMMMAAAATTTTCCCCHHHHIIIINNNNGGGG AAAA    PPPPAAAATTTTTTTTEEEERRRRNNNN
  105.       The function rrrreeeeggggeeeexxxxeeeecccc(((()))) is called to match a pre-compiled
  106.       pattern _p_r_e_g against a given _s_t_r_i_n_g, which is    terminated by
  107.       a zero byte, subject to the options in _e_f_l_a_g_s. These can be:
  108.  
  109.         REG_NOTBOL
  110.  
  111.       The PCRE_NOTBOL option is set    when calling the underlying
  112.       PCRE matching    function.
  113.  
  114.         REG_NOTEOL
  115.  
  116.       The PCRE_NOTEOL option is set    when calling the underlying
  117.       PCRE matching    function.
  118.  
  119.       The portion of the string that was matched, and also any
  120.       captured substrings, are returned via    the _p_m_a_t_c_h argument,
  121.       which    points to an array of _n_m_a_t_c_h structures    of type
  122.       _r_e_g_m_a_t_c_h__t, containing the members _r_m__s_o and _r_m__e_o. These
  123.       contain the offset to    the first character of each substring
  124.       and the offset to the    first character    after the end of each
  125.       substring, respectively. The 0th element of the vector
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 12/10/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      PPPPCCCCRRRREEEE((((3333))))               UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV               PPPPCCCCRRRREEEE((((3333))))
  137.  
  138.  
  139.  
  140.       relates to the entire    portion    of _s_t_r_i_n_g that was matched;
  141.       subsequent elements relate to    the capturing subpatterns of
  142.       the regular expression. Unused entries in the    array have
  143.       both structure members set to    -1.
  144.  
  145.       A successful match yields a zero return; various error codes
  146.       are defined in the header file, of which REG_NOMATCH is the
  147.       "expected" failure code.
  148.  
  149.  
  150.  
  151.      EEEERRRRRRRROOOORRRR MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS
  152.       The rrrreeeeggggeeeerrrrrrrroooorrrr(((()))) function maps a non-zero errorcode from
  153.       either rrrreeeeggggccccoooommmmpppp or rrrreeeeggggeeeexxxxeeeecccc to a printable message. If _p_r_e_g is
  154.       not NULL, the    error should have arisen from the use of that
  155.       structure. A message terminated by a binary zero is placed
  156.       in _e_r_r_b_u_f. The length    of the message,    including the zero, is
  157.       limited to _e_r_r_b_u_f__s_i_z_e. The yield of the function is the
  158.       size of buffer needed    to hold    the whole message.
  159.  
  160.  
  161.  
  162.      SSSSTTTTOOOORRRRAAAAGGGGEEEE
  163.       Compiling a regular expression causes    memory to be allocated
  164.       and associated with the _p_r_e_g structure. The function
  165.       rrrreeeeggggffffrrrreeeeeeee(((()))) frees all such memory, after which _p_r_e_g may    no
  166.       longer be used as a compiled expression.
  167.  
  168.  
  169.  
  170.      AAAAUUUUTTTTHHHHOOOORRRR
  171.       Philip Hazel <ph10@cam.ac.uk>
  172.       University Computing Service,
  173.       New Museums Site,
  174.       Cambridge CB2    3QG, England.
  175.       Phone: +44 1223 334714
  176.  
  177.       Copyright (c)    1998 University    of Cambridge.
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 12/10/98)
  196.  
  197.  
  198.  
  199.